ApplicationSet Specification

The following describes all the available fields of an ApplicationSet:

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ApplicationSet
  3. metadata:
  4.   name: test-hello-world-appset
  5.   namespace: argocd
  6.   # To preserve this annotation and label we can use the preservedFields property 
  7.   preservedFields:
  8.     # This annotation and label exists only on this Application, and not in 
  9.     # the parent ApplicationSet template:
  10.     # ignoreApplicationDifferences is the preferred way to accomplish this now.
  11.     annotations: 
  12.       my-custom-annotation: some-value
  13.     labels:
  14.       my-custom-label: some-value
  16. spec:
  17.   generators:
  19.     # Using a generator plugin without combining it with Matrix or Merge
  20.     # Plugins allow you to provide your own generator
  21.     - plugin:
  22.       # Specify the configMap where the plugin configuration is located.
  23.       configMapRef:
  24.         name: my-plugin
  25.       # You can pass arbitrary parameters to the plugin. `input.parameters` is a map, but values may be any type.
  26.       # These parameters will also be available on the generator's output under the `generator.input.parameters` key.
  27.       input:
  28.         parameters:
  29.           key1: "value1"
  30.           key2: "value2"
  31.           list: ["list", "of", "values"]
  32.           boolean: true
  33.           map:
  34.             key1: "value1"
  35.             key2: "value2"
  36.             key3: "value3"
  37.         # You can also attach arbitrary values to the generator's output under the `values` key. These values will be
  38.         # available in templates under the `values` key.
  39.         values:
  40.           value1: something
  41.         # When using a Plugin generator, the ApplicationSet controller polls every `requeueAfterSeconds` interval (defaulting to every 30 minutes) to detect changes.
  42.         requeueAfterSeconds: 30
  44.     # to automatically discover repositories within an organization
  45.     - scmProvider:
  46.         # Which protocol to clone using.
  47.         cloneProtocol: ssh
  48.         # The GitHub mode uses the GitHub API to scan an organization in either github.com or GitHub Enterprise
  49.         github:
  50.           # The GitHub organization to scan.
  51.           organization: myorg
  52.           # For GitHub Enterprise:
  53.           api: https://git.example.com/
  54.           # If true, scan every branch of every repository. If false, scan only the default branch. Defaults to false.
  55.           allBranches: true
  56.           # Reference to a Secret containing an access token. (optional)
  57.           tokenRef:
  58.             secretName: github-token
  59.             key: token
  60.           # (optional) use a GitHub App to access the API instead of a PAT.
  61.           appSecretName: gh-app-repo-creds
  62.           #Pass additional key-value pairs via values field
  63.           values:
  64.             name: "{{organization}}-{{repository}}"
  66.         #The GitLab mode uses the GitLab API to scan and organization in either gitlab.com or self-hosted GitLab.  
  67.         gitlab:
  68.         #The Gitea mode uses the Gitea API to scan organizations in your instance
  69.         gitea:
  70.         #Use the Bitbucket Server API (1.0) to scan repos in a project.
  71.         bitbucketServer:
  72.         #Uses the Azure DevOps API to look up eligible repositories 
  73.         azureDevOps:
  74.         # The Bitbucket mode uses the Bitbucket API V2 to scan a workspace in bitbucket.org
  75.         bitbucket:
  76.         #Uses AWS ResourceGroupsTagging and AWS CodeCommit APIs to scan repos across AWS accounts and regionsz
  77.         awsCodeCommit:
  79.         #Filters allow selecting which repositories to generate for. 
  80.         filters:
  81.         # Include any repository starting with "myapp" AND including a Kustomize config AND labeled with "deploy-ok" ...
  82.         - repositoryMatch: ^myapp
  83.           pathsExist: [kubernetes/kustomization.yaml]
  84.           labelMatch: deploy-ok
  85.         # ... OR include any repository starting with "otherapp" AND a Helm folder and doesn't have file disabledrepo.txt.
  86.         - repositoryMatch: ^otherapp
  87.           pathsExist: [helm]
  88.           pathsDoNotExist: [disabledrepo.txt]
  89.     # matrix 'parent' generator
  90.     - matrix:
  91.         generators:
  92.         # any of the top-level generators may be used here instead.
  94.     # merge 'parent' generator
  95.     # Use the selector set by both child generators to combine them.
  96.     - merge:
  97.         mergeKeys:
  98.           - server
  99.           # Note that this would not work with goTemplate enabled,
  100.           # nested merge keys are not supported there.
  101.           - values.selector
  102.         generators:
  103.           - clusters:
  104.               values:
  105.                 kafka: 'true'
  106.                 redis: 'false'
  107.           # For clusters with a specific label, enable Kafka.
  108.           - clusters:
  109.               selector:
  110.                 matchLabels:
  111.                   use-kafka: 'false'
  112.               values:
  113.                 kafka: 'false'
  114.           # For a specific cluster, enable Redis.
  115.           - list:
  116.               elements: 
  117.                 - server: https://2.4.6.8
  118.                   values.redis: 'true'
  121.   # Determines whether go templating will be used in the `template` field below.
  122.   goTemplate: true
  123.   # Optional list of go templating options, see https://pkg.go.dev/text/template#Template.Option
  124.   # This is only relevant if `goTemplate` is true
  125.   goTemplateOptions: ["missingkey=error"]
  127.   # These fields are identical to the Application spec.
  128.   # The generator's template field takes precedence over the spec's template fields
  129.   template:
  130.     metadata:
  131.       name: test-hello-world-app
  132.     spec:
  133.       project: my-project
  134.       syncPolicy: 
  135.         automated:
  136.           selfHeal: true    
  137.         syncOptions:
  138.         - CreateNamespace=true  
  139.       # defines from which Git repository to extract the desired Application manifests
  140.       source:
  141.         - chart: '{{.chart}}'
  142.         # developers may customize app details using JSON files from above repo URL
  143.           repoURL: https://github.com/argoproj/argo-cd.git
  144.           targetRevision: HEAD
  145.           # Path within the repository where Kubernetes manifests are located
  146.           path: applicationset/examples/list-generator/guestbook/{{cluster}}
  147.           helm:
  148.             useCredentials: "{{.useCredentials}}"  # This field may NOT be templated, because it is a boolean field
  149.           parameters:
  150.           - name: "image.tag"
  151.             value: "pull-{{head_sha}}"
  152.           - name: "{{.name}}"
  153.             value: "{{.value}}"
  154.           - name: throw-away
  155.             value: "{{end}}"
  156.       destination:
  157.         # Only one of name or server may be specified: if both are specified, an error is returned.
  158.         #  Name of the cluster (within Argo CD) to deploy to
  159.         name: production-cluster # cluster is restricted
  160.         #  API Server URL for the cluster
  161.         server: '{{.url}}'
  162.         # Target namespace in which to deploy the manifests from source 
  163.         namespace: dev-team-one # namespace is restricted
  165.   # This sync policy pertains to the ApplicationSet, not to the Applications it creates.
  166.   syncPolicy:
  167.     # Prevents ApplicationSet controller from modifying or deleting Applications
  168.     applicationsSync: create-only
  170.     # Prevents ApplicationSet controller from deleting Applications. Update is allowed
  171.   # applicationsSync: create-update
  173.     # Prevents ApplicationSet controller from modifying Applications. Delete is allowed.
  174.   # applicationsSync: create-delete
  176.     syncOptions:
  177.     - CreateNamespace=true
  178.     # Prevent an Application's child resources from being deleted, when the parent Application is deleted
  179.     preserveResourcesOnDeletion: true
  181.     # which fields of the ApplicationSet should be ignored when comparing Applications.
  182.     ignoreApplicationDifferences:
  183.     - jsonPointers:
  184.         - /spec/source/targetRevision
  185.     - name: some-app
  186.       jqExpressions:
  187.         - .spec.source.helm.values
  189.   strategy:
  190.   # This field lets you define fields which should be ignored when applying Application resources. This is helpful if you
  191.   # want to use ApplicationSets to create apps, but also want to allow users to modify those apps without having their
  192.   # changes overwritten by the ApplicationSet.
  193.      # This update strategy allows you to group Applications by labels present on the generated Application resources
  194.      type: RollingSync
  195.      rollingSync:
  196.       steps:
  197.         # Application groups are selected using their labels and matchExpressions
  198.         - matchExpressions:
  199.             - key: envLabel
  200.               operator: In
  201.               values:
  202.                 - env-dev
  203.         # maxUpdate: 100%  # if undefined, all applications matched are updated together (default is 100%)
  204.         - matchExpressions:
  205.             - key: envLabel
  206.               operator: In
  207.               values:
  208.                 - env-qa
  209.           maxUpdate: 0      # if 0, no matched applications will be synced unless they're synced manually
  210.         - matchExpressions:
  211.             - key: envLabel
  212.               operator: In
  213.               values:
  214.                 - env-prod
  215.           maxUpdate: 10%    # maxUpdate supports both integer and percentage string values (rounds down, but floored at 1 Application for >0%)
  217.   ignoreApplicationDifferences:
  218.   - jsonPointers:
  219.     - /spec/source/targetRevision
  220.   - name: some-app
  221.     jqPathExpressions:
  222.     - .spec.source.helm.values
  224.   # Cluster-decision-resource-based ApplicationSet generator
  225.   - clusterDecisionResource:
  226.     # ConfigMap with GVK information for the duck type resource
  227.     configMapRef: my-configmap  
  228.     name: quak           # Choose either "name" of the resource or "labelSelector"
  229.     labelSelector:
  230.       matchLabels:       # OPTIONAL
  231.         duck: spotted
  232.       matchExpressions:  # OPTIONAL
  233.       - key: duck
  234.         operator: In
  235.         values:
  236.         - "spotted"
  237.         - "canvasback"   
  238.     # OPTIONAL: Checks for changes every 60sec (default 3min)
  239.     requeueAfterSeconds: 60
  241.   # The Pull Request generator uses the API of an SCMaaS provider to automatically discover open pull requests within a repository
  242.   - pullRequest:
  243.       # When using a Pull Request generator, the ApplicationSet controller polls every `requeueAfterSeconds` interval (defaulting to every 30 minutes) to detect changes.
  244.       requeueAfterSeconds: 1800
  245.       # See below for provider specific options.
  246.       # Specify the repository from which to fetch the GitHub Pull requests.
  247.       github:
  248.         # The GitHub organization or user.
  249.         owner: myorg
  250.         # The Github repository
  251.         repo: myrepository
  252.         # For GitHub Enterprise (optional)
  253.         api: https://git.example.com/
  254.         # Reference to a Secret containing an access token. (optional)
  255.         tokenRef:
  256.           secretName: github-token
  257.           key: token
  258.         # (optional) use a GitHub App to access the API instead of a PAT.
  259.         appSecretName: github-app-repo-creds
  260.         # Labels is used to filter the PRs that you want to target. (optional)
  261.         labels:
  262.         - preview
  264.       # Filters allow selecting which pull requests to generate for
  265.       # Include any pull request ending with "argocd". (optional)
  266.       filters:
  267.       - branchMatch: ".*-argocd"
  269.       # Specify the project from which to fetch the GitLab merge requests.
  270.       gitlab:
  271.       # Specify the repository from which to fetch the Gitea Pull requests.
  272.       gitea:
  273.       # Fetch pull requests from a repo hosted on a Bitbucket Server (not the same as Bitbucket Cloud).
  274.       bitbucketServer:
  275.       # Fetch pull requests from a repo hosted on a Bitbucket Cloud.
  276.       bitbucket:
  277.       # Specify the organization, project and repository from which you want to fetch pull requests.
  278.       azuredevops:
  279.       # Fetch pull requests from AWS CodeCommit repositories.
  280.       awsCodeCommit:
  282. # The list generator generates a set of two application which then filter by the key value to only select the env with value staging
  283.   - list:
  284.       elements:
  285.         - cluster: engineering-dev
  286.           url: https://kubernetes.default.svc
  287.           env: staging
  288.         - cluster: engineering-prod
  289.           url: https://kubernetes.default.svc
  290.           env: prod
  291.       # The generator's template field takes precedence over the spec's template fields
  292.       template:
  293.         metadata: {}
  294.         spec:
  295.           project: "default"
  296.           source:
  297.             revision: HEAD
  298.             repoURL: https://github.com/argoproj/argo-cd.git
  299.             # New path value is generated here:
  300.             path: 'applicationset/examples/template-override/{{cluster}}-override'
  301.           destination: {}
  303.     selector:
  304.       matchLabels:
  305.         env: staging
  306.   # It is also possible to use matchExpressions for more powerful selectors
  307.   - clusters: {}
  308.     selector:
  309.       matchExpressions:
  310.         - key: server
  311.           operator: In
  312.           values:
  313.             - https://kubernetes.default.svc
  314.             - https://some-other-cluster